<?php
/**
 * This file contains classes implementing security manager feature.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.yiiframework.com/
 * @copyright Copyright &copy; 2008-2011 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

/**
 * CStatePersister implements a file-based persistent data storage.
 *
 * It can be used to keep data available through multiple requests and sessions.
 *
 * By default, CStatePersister stores data in a file named 'state.bin' that is located
 * under the application {@link CApplication::getRuntimePath runtime path}.
 * You may change the location by setting the {@link stateFile} property.
 *
 * To retrieve the data from CStatePersister, call {@link load()}. To save the data,
 * call {@link save()}.
 *
 * Comparison among state persister, session and cache is as follows:
 * <ul>
 * <li>session: data persisting within a single user session.</li>
 * <li>state persister: data persisting through all requests/sessions (e.g. hit counter).</li>
 * <li>cache: volatile and fast storage. It may be used as storage medium for session or state persister.</li>
 * </ul>
 *
 * Since server resource is often limited, be cautious if you plan to use CStatePersister
 * to store large amount of data. You should also consider using database-based persister
 * to improve the throughput.
 *
 * CStatePersister is a core application component used to store global application state.
 * It may be accessed via {@link CApplication::getStatePersister()}.
 * page state persistent method based on cache.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: CStatePersister.php 3165 2011-04-06 08:27:40Z mdomba $
 * @package system.base
 * @since 1.0
 */
class CStatePersister extends CApplicationComponent implements IStatePersister
{
    /**
     * @var string the file path storing the state data. Make sure the directory containing
     * the file exists and is writable by the Web server process. If using relative path, also
     * make sure the path is correct.
     */
    public $stateFile;
    /**
     * @var string the ID of the cache application component that is used to cache the state values.
     * Defaults to 'cache' which refers to the primary cache application component.
     * Set this property to false if you want to disable caching state values.
     * @since 1.0.10
     */
    public $cacheID='cache';

    /**
     * Initializes the component.
     * This method overrides the parent implementation by making sure {@link stateFile}
     * contains valid value.
     */
    public function init()
    {
        parent::init();
        if($this->stateFile===null)
        $this->stateFile=Yii::app()->getRuntimePath().DIRECTORY_SEPARATOR.'state.bin';
        $dir=dirname($this->stateFile);
        if(!is_dir($dir) || !is_writable($dir))
        throw new CException(Yii::t('yii','Unable to create application state file "{file}". Make sure the directory containing the file exists and is writable by the Web server process.',
        array('{file}'=>$this->stateFile)));
    }

    /**
     * Loads state data from persistent storage.
     * @return mixed state data. Null if no state data available.
     */
    public function load()
    {
        $stateFile=$this->stateFile;
        if($this->cacheID!==false && ($cache=Yii::app()->getComponent($this->cacheID))!==null)
        {
            $cacheKey='Yii.CStatePersister.'.$stateFile;
            if(($value=$cache->get($cacheKey))!==false)
            return unserialize($value);
            else if(($content=@file_get_contents($stateFile))!==false)
            {
                $cache->set($cacheKey,$content,0,new CFileCacheDependency($stateFile));
                return unserialize($content);
            }
            else
            return null;
        }
        else if(($content=@file_get_contents($stateFile))!==false)
        return unserialize($content);
        else
        return null;
    }

    /**
     * Saves application state in persistent storage.
     * @param mixed $state state data (must be serializable).
     */
    public function save($state)
    {
        file_put_contents($this->stateFile,serialize($state),LOCK_EX);
    }
}
